quanser.communications.stream.scan
Scans formatted text from a stream.
[code_units, num_fields, mismatch, would_block, ...] = stream.scan(max_code_units, format_string, ...)
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.
This function does not support code generation.
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.
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.
[num_chars, num_fields, mismatch, wb, x] = stream.scan(80, 'X: %lf'); % Scans the value of x from the stream
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.