#

# LogiView

## Function 'scan'

| This function splits up a forwarded string into individual substrings which are assigned to corresponding variables according to the type by means of conversion. The result is the number of sucessfully assigned variables. The function is aborted if the format character string has been comletely processed or if a field in the input string is not appropriate to the conversion specifications. A substring extends to the next space, tab (\t) or line break (\n) or to an explicitely specified field width. Every conversion specification starts with the % character and ends with a conversion character. The space between % and the conversion character could contain the following (in sequence):
* | An asterisk preventing the allocation of a field to a variable. (In this case the number of output variables is lower than the number of fields in the input string.)
Value | A value specifying the maximum field width.
| The following letters are used as conversion characters:
i, d | Converts a field to an integer expression.
f | Converts a field to a float expression in float-point representation with six digits behind the decimal point. Rounding errors cannot be excluded.
s | Converts a field to a string expression. In this case only the explicitely specified field width is queried if necessary.
l | Converts a field to a logic expression. The following fields can be converted to the logic value 'TRUE': TRUE, Y, y, J, j, O, o.
| The following fields can be converted to the logic value 'FALSE': FALSE, N, n.
| If a substring in the input string does not correspond to a conversion character, the function is aborted. However, in this case no error is returned because the function only returns the number of successfully converted fields. In general, the 'scan' function could be compared with the 'sscanf' function of the C programming language. This function must be called in the action part only!
| ### Syntax:
| {INT_VAR}= scan({STR_EXPR},{STR_EXPR},{VAR_LIST})
| ### I/O parameters:
| {STR_EXPR} | Input string
| {STR_EXPR} | Format character string (string expression)
| {VAR_LIST} | Output variables, assigned with the converted fields of the input string (types according to the corresponding field).
| {INT_VAR} | Number of assigned substrings
| ### Example 1:
| Declaration of Variables
     10 DOCU_STRING_1 = "45.5 |ABCD 4711 | 33mm"
     20 DOCU_INT_1 = scan(DOCU_STRING_1,"%f %*s %4s | %i",
                          DOCU_FLOAT_1, DOCU_STRING_2,DOCU_INT_2)
     30 put(DOCU_FLOAT_1,DOCU_STRING_2,DOCU_INT_2)
| Result:
Substring | 45.5 | |ABCD | 4711 | | | 33mm
Format character string (string expression) | %f | %*s | %4s | | | %i
Explanation | The substring is converted to a float value | The substring is skipped due to the "*" character. | The substring is converted to 4-digit string value | The substring is skipped due to an aquainted character. | The substring is converted to an integer value
Variables | DOCU_FLOAT_1 | - | DOCU_STRING_2 | - | DOCU_INT_2
Allocation | 45.5000000 | - | 4711 | - | 33
| Besides the conversion information '%i', '%f', '%l' and '%s' also regular expressions contained in the C standard function 'sscanf' are supported. A LogiView string variable must always be included as related output argument. The following conversion information can be used:
%[Character] | Displays only those characters included in the brackets.
%[^Character] | Displays only those characters not included in the brackets.
| The list of characters corresponds to a simple listing or a (ascending) range:
ABCDabcd or A-Da-d | The first four characters of the alphabet in upper case or lower case.
0123456789 or 0-9 | only numbers
It is possible to combine both possibilities.
| ### Example 2:
| Declaration of Variables
     10   DOCU_STRING_1 = "abc*\defg"
     20 C -- No special characters must be used
     30   DOCU_INT_1 = scan(DOCU_STRING_1,"%[A-Za-z0-9]", DOCU_STRING_2)
     40   put(DOCU_STRING_2)
| Result:
| Functions and commands: Editing Strings