String Scan

Scans formatted data from a stream.

Library

QUARC Targets/Strings

Description

The String Scan block scans formatted data from a string, much like sscanf scans a string. The input is a UTF-8 string expressed as a null-terminated vector of uint8 characters. The output of any of the QUARC blocks that support strings is compatible with the String Scan block.

For a description of the format strings, refer to Format Strings for Scanning.

This block reads from the string and parses the textual data according to the given format string and then presents the parsed values at its outputs.

If an error occurs, then it returns a negative error code at its err output. If no error occurs then the number of code units (bytes) scanned is presented at the err output. The Compare to Error block may be used to check for specific error codes.

If the input does not match the format string, then the inv output (i.e. "invalid") is set to true.

The number of fields parsed successfully and fully is indicated by the flds output.

The flds output may be non-zero even when a mismatch occurs between the input and the format string. In this case, only those outputs corresponding to the successfully parsed fields will be valid. Outputs for fields not parsed successfully are indeterminate, and will not necessarily equal the last value successfully parsed.

Helpful Hints

Skipping to the end of a line

To skip to the end of a line to ignore invalid input, use a format string of " %*[^\n]", which ignores all characters in the input up to the next newline. Take careful note of the leading space character, which is needed to skip the whitespace at the end of the last valid line.

Input Ports

str

A UTF-8 string expressed as a null-terminated vector of uint8 characters. It is typically the output of one of the other QUARC blocks which supports strings. It may be a variable-size signal. See Variable-Size Signals for more information on variable-size signals.

...

Subsequent input ports are used for variable field width and variable maximum code unit specifiers, such as "%.*s" or "%s[*] respectively in the format string.

Output Ports

...

The first output ports contain the data parsed. The number of output ports is determined by the number of format specifiers, such as %lf, in the specified format string. If a format specifier contains an '*' after the '%' to suppress assignment to an output, then no output is created for that format specifier, and that field will not be included in the count of fields scanned. Variable-sized code unit specifiers cause input ports to be created in order to specify the maximum number of code units.

flds

An int32 value indicating the number of fields from the format string that were read from the string successfully and fully. This number may be less than the number of fields defined in the format string if the maximum number of code units was reached before all the fields were read from the string. If an error occurs, then this value indicates the number of fields that could be read successfully, which may assist in locating the source of the error.

inv

A Boolean value indicating whether the input was invalid according to the format string. The flds output will indicate the number of fields that were parsed successfully before the input failed to match the format string. This output is true (non-zero) if the input did not match the format string. Otherwise it is false (zero). Note that when the input fails to match the format string, the err output will be zero and the inv output will be true, so that only critical errors are reported at the err output.

err

An int32 value indicating whether the formatted text was read from the string successfully. It will be the number of code units read unless an error occurs. If an error occurs then this value is a negative error code. If the iput from the stream does not match the format string then -QERR_MISMATCHED_CHARACTER is returned. If the stream is non-blocking and the formatted text could not be read from the stream buffer then -QERR_WOULD_BLOCK is output. See Error Codes for the different error codes and their values. Use the Compare to Error block rather than the error code itself to check for specific error codes. To check for errors in general use the Compare to Zero block to check whether err output is less than zero.

Data Type Support

The String Scan block outputs signals of any of the built-in Simulink data types at its data outputs. The data type is determined by the format specifiers in the format string. Fixed point is not currently supported. A variable-size signal at the str input is supported. See Variable-Size Signals for more information on variable-size signals.

For array quantities, as indicated by a dimension specifier in the format string, the String Scan block outputs vector signals of the data type corresponding to the format specifier at that port.

Parameters and Dialog Box

Format string

The format string used to parse the data. Refer to the Format Strings for Scanning page for a description of the format string. This parameter is treated as a string literal. It is not evaluated. Hence, do not enclose the format string in quotes unless you wish the quotes to appear in the input.

Maximum number of code units to scan

This parameter restricts the total number of code units read from the string. This limit is a hard limit. The total number of code units read from the stream will never exceed this limit, even if a field is truncated.

Targets

See Also

• Format Strings for Scanning
• String Print block
• String Constant block
• String Display block

Copyright ©2024 Quanser Inc. This page was generated 2024-04-16. Submit feedback to Quanser about this page.

Link to this page.