quanser.communications.stream.receive_double_array quanser.communications.stream.scan_array navigation bar

Table of Contents

quanser.communications.stream.scan

Scans formatted text from a stream.

Syntax

[code_units, num_fields, mismatch, would_block, ...] = stream.scan(max_code_units, format_string, ...)
    

Description

This function scans formatted text from the stream, much like fscanf scans a file. It reads from the input stream and parses the textual data according to the given format string and returns the parsed values at its output. String format specifiers must include a field width to indicate the maximum length of the string.

The stream receive buffer must be large enough to hold the text for each individual field scanned while processing the format string. The size may need to be larger than expected because parsing the text often requires "looking ahead" additional characters to determine where the actual field ends.

If the input does not match the format string, then mismatch is set to true (1) and the stream is only advanced as far as the end of the last character or field that successfully matched the format string. The number of fields successfully scanned is returned. Hence, the stream can be rescanned after a formatting mismatch but scanning will begin after the last field successfully scanned. This behaviour differs from the scan_array function, which does not advance the stream at all if the input does not match the format string and hence allows the entire string to be rescanned.

The stream may also be rescanned if would_block is true (1), indicating that the stream is in non-blocking mode and there were not enough characters available to scan the format string and reading more characters from the stream would have blocked. Some of the fields may have been scanned successfully, as indicated by the fields output, in which case the stream is advanced as far as the end of the last character or field successfully scanned.

If an error occurs, then it issues an error message and the stream should be closed. If the connection is closed then it is considered an error condition.

If quanser.communications.stream.listen or quanser.communications.stream.connect was called with the non-blocking flag set to false (0), then this function may block attempting parse the stream. If parsing the input stream required "looking ahead" then the additional characters remain in the stream receive buffer until the next scan operation.

If quanser.communications.stream.listen or quanser.communications.stream.connect was called with the non-blocking flag set to true (1), then this function does not block. It returns the number of code units parsed successfully. If the full format string could not be scanned without blocking, then would_block is set to true (1).

This operation is not valid on listening streams created using quanser.communications.stream.listen.

Warning This function does not support code generation.

Parameters

stream

Stream handle returned by quanser.communications.stream.connect or accept.

max_code_units

The maximum number of code units to read from the underlying stream. 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.

format_string

A format string akin to the C library function fscanf. Note however that more options are available, such as the ability to scan arrays using a single format specifier. Refer to Format Strings for Scanning for details on format strings.

...

Additional arguments corresponding to variable field width, variable maximum code unit and variable dimension specifiers in the format string.

Outputs

code_units

The number of code units actually read from the stream.

num_fields

The number of fields actually read completely from the stream, which may be less than the number of fields in the format string for non-blocking streams and for blocking streams in which the maximum number of code units was reached before all the fields were read from the stream buffer.

mismatch

Whether the input matched the format string.

would_block

Whether the function would have blocked. Always false for blocking streams.

...

Additional output arguments corresponding to each format specifier in the format string that does not have the assignment suppression flag set.

Examples

[num_chars, num_fields, mismatch, wb, x] = stream.scan(80, 'X: %lf');    % Scans the value of x from the stream
    

See Also

 

navigation bar