Library Function li_ckvar

function [sErrMsg, xVarAdjusted] = li_ckvar(xVar, sReqType, varargin)

Checks <xVar> to heed the type definition passed in <sReqType>. If the check was passed, output <sErrMsg> will be an empty string, otherwise it will contain an appropriate error message containing a %s placeholder for the name or a respectively passed description of the argument tested. A second output argument might be assigned that will contain an empty matrix ([]) if the test failed, and the tested argument - optionally adjusted - if the test was passed. Additional arguments might be passed as name-value pairs. Many of these additional arguments are specific to one or more <sReqType> arguments. If passed with an inappropriate <sReqType>, a name-value pair will be ignored. If passed multiple times, the value passed with the first occurence will be used. An option common to all types is '--var-name' that defines the name or description of the variable to be used in error messages.

<sReqType> values and associated options ______________________________________________________________________________________________________________________

'bool' The tested variable is expected to be interpretable as a boolean (true or false) value. By default strings or row vectors of char equalling case insensitive 'true', 'yes' or 'on' are considered true and respectively 'false', 'no' or 'off' are considered false, any other values of these types return an error message. Integer types are valid only if eqalling 0 for false or 1 for true, barring options. Floating point types are valid only if differing from 0 no more than 10*eps for false and respectively 10*psi from 1 for true, barring options. All numeric types are never valid, if they contain any element with imaginary part unequal to zero. Matlab®'s logical type is always accepted as is. By default any input dimension is accepted with the exception of char that is only allowed to be a row vector and thus can only represent a scalar boolean value. If a second return value is present, it will be a respective logical scalar or array if the check was successful, and empty othwerwise. - Option '--no-str', if set to true, does not allow char or string representations. - Option '--no-int', if set to true, does not allow integer representations. - Option '--no-float', if set to true, does not allow floating representations. - Option '--no-numeric', if set to true, does not allow any numeric representations. - Option '--scalar-only', if set to true, does only allow representations that evaluate to a scalar boolean value. - Option '--loose-numeric', if set to true, any numeric value that does not evaluate to true is considered false. - Option '--sharp-float', if set to true, only allows exact 0 or 1 for floating types. Might be combined with --loose option, where anything but exact 0 evaluates to true, though this is not recommended.

'file-read', 'file-write', 'file-append', 'dir-read' or 'dir-write' The tested value is expected to represent one or more file objects. By default a scalar string or a row vector of char forming the path of a single file object is is required. The required type values starting on 'file-' expect representations of a regular files, those starting on 'dir-' such of directories. The required type values ending on '-read' expect representations of file objects that exist and are readable by the current user, where in case of directories reading means the listing of its contents in general. The required type values ending on '-write' or '-append' expect file objects, that can be written into with the current users previliges. If the creation of any directories would be required to do so, this is only allowed along with the option --create-all. Type values 'file-write' and 'file-append' are the same appart from handles going in or out of the check. For an incoming handle it would be expected to have been opened for writing or appending respectively, for --return-type 'handle' a respective handle would be opened using the required mode, where necessary. Incoming machine format is always ignored, outgoing always the default, if opened by this utility. - Option '--allow-array' If true, representation of multiple files are allowed. Where string types are allowed this might be arrays of string or cell arrays of row vector chars. Where handles are allowed, this might be arrays of Matlab® file handles (usually positive integers of class double). Default is false. - Option '--allow-handle' If true, in addition to string types also Matlab® file handles are allowed. Default is false. - Option '--handles-only' If true, only Matlab® file handles ar allowed. Default is false. - Option '--create-all' Might only be set to true with required types ending on '-write'. If any ancestor directory is missing, it will be created as far as permissions allow it. Default is false. - Option '--return-type' Might be 'handle', 'char', 'string-only' or 'string'. If a 2nd output argument is present and the input variable passed all tests, said argument will contain the variable under test converted into the respective format. If 'string-only' is passed and Matlab® strings are not available on the platform, a respective error message will be passed back. If 'string' is passed and Matlab® strings are not available, char or cell array of char is returned instead. Default is 'char'. If --return-type is 'char' and the input is non-scalar, a respective cell array of row vector chars will be returned. If the input consists of one or more handles, and the return type evaluates to 'string' or 'char', the returned file paths might be relative, as only the path passed to fopen is available from Matlab® file handles and the base directory (usually the current directory at the time of calling fopen) can't be reconstructed. Returned paths are lexically normalised.

'sl-obj' The tested value is expected to represent one or more simulink modelling objects. By default this can be an array of any size consisting of either valid simulink object handles or actual simulink objects, as well as char or string representations of simulink block paths pointing to existing simulink items, inluding cell arrays of char. Any reference to a deleted object is not allowed. Cell arrays might only contain row vectors of char, any mixing up with Matlab®'s string type or any other representatioj is currently not allowed. If a second return value is present, it will be a respective scalar or array of numeric handles, if the check was successful, and empty othwerwise. Simulink modelling objects are only such objects, that directly make up a simulink model, like blocks, line, annotations. Other types representing e.g. parameters, parameter classes or auxiliary objects, like Simulink.IntEnumType or Simulink.BlockPath are generally not accepted. - Option '--no-str' If true, no string or char representations, including cell arrays of char, are allowed. Default is false. - Option '--no-obj' If true, no objects of a subclass of the Simulink package are allowed. Default is false. - Option '--no-hdl' If true, no numeric handles to simulink objects are allowed. Default is false. - Option '--scalar-only' If true, only a representation of a single (scalar) simulink object is allowed. Default is false. - Option '--try-load' If true, in case of char or string block paths it will be tried to load the simulink object, if not yet loaded. Default is false. - Option '--sl-type' If not empty, only the passed type string will be allowed. This refers to the 'Type' property that might have values like 'block', 'block_diagram' or 'port', but also values of subtypes like 'outport' found in 'PortType' property might be passed. Default is empty (''). If more than one simulink object reference is passed and '--sl-type' is not empty, the 'Type' property must be the same for all of them, even if there might be overlapping subtype names. The search is case-sensitive, thus e.g. 'outport' will only match port's 'PortType' parameter, and 'Outport' only blocks of respective 'BlockType'. - Option '--ret-type' Might be 'path', 'handle', 'object' or 'keep'. If a 2nd output argument is present and the input variable passed all tests, said argument will contain the variable under test converted into the respective format. Option 'path' might yield empty strings where simulink objects have no path representations like lines and texts.

'text' This type value is generally the same as 'text-line', only that it does not restrict the tested variable to represent a kind of line, here any number and size of dimensions is allowed. Also all options from 'text-line' are shared, with one option added. - All options from 'text-line'. The '--ret-type' values 'ms-string' and 'ms-string-only' are only allowed along with the '--concat' option, as the Matlab® integration of ms.net objects only allows for scalars. - Option '--concat' Here, as far as all tests are passed and a second output is assigned, all elements of the tested variables are concatenated, using the value of the option as separator and the result is assigned to the adjusted variable in the required format. Concatenation is done first along the column indices (2nd dimension), then along the row indices (1st dimension), and then - if present - along the higher dimensions in ascending order. For the row vector types as defined for 'text-line' the seperator will not be inserted between the columns of a row. The separator might be an empty char or row vector of char, or a scalar string with an empty or non-empty element. For uint8, int8 or java.lang.StringBuilder inputs and '--ret-type' 'keep' the '--concat' option is not allowed (These types are also not available with the '--ret-type' option, they might only be handed through unprocessed).

'text-line' The tested variable is expected to be of a type and shape that makes it interpretable as a line of text. By default allowed are row vectors of char or uint8 or int8 and scalars of string or java.lang.String or java.lang.StringBuilder or System.String. The integer types must contain all numbers out of the range of printable 7-Bit ASCII plus CR, LF, TAB. All row vector types might be empty, barring options. All other types might not be empty, but might contain an empty string, barring options. Some types might be excluded by options. All values received in <xVar> or returned in <xVarAdjusted> might still contain newline characters and under that aspect represent more than one single line. There is no check for newline characters. - Option '--ret-type' The value passed might be 'char', 'string', 'string-only', 'java-string', 'java-string-only', 'ms-string', 'ms-string-only' or 'keep'. Any other value for this option will throw an error. In case of 'keep' the <xVar> type is kept with <xVarAdjusted>. If another value is passed, the second output will be <xVar> converted to the respective type. Some platforms or releases do not support all types. In such cases an error will be thrown, if the required but unsupported type value ends on '-only'. Otherwise a conversion to a row vector of char will be applied instead. Default is 'char'. - Option '--non-empty' If true, does not allow an empty string with the scalar types and neither an empty array with the row vector types. Default is false. - Option '--no-java' If true, does not allow java types java.lang.String and java.lang.StringBuilder. Default is false. - Option '--no-ms' If true, does not allow Microsoft .net type System.String. Default is false. - Option '--no-int' If true, does not allow the integer row vector types. Default is false. - Option '--no-string' If true, does not allow the builtin string type. Default is false. - Option '--matlab-types-only' If true, does only allow Matlab®'s builtin types. That is always row vector of char, and in case of availability, string, row vector of uint8 and row vector of int8. Default is false.