stream_scan_array
Scans formatted text from a stream as an atomic unit.
[code_units, fields, mismatch, would_block, ...] = stream_scan_array(stream, max_code_units, format_string, ...)
This function scans formatted text from the stream, much like fscanf scans
a file, but as an atomic unit. 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 all the text 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 not advanced. Hence, the stream can be rescanned after a formatting mismatch. This behaviour differs from the stream_scan function, which advances the stream up to the end of the last character or field successfully scanned.
The stream may also be rescanned if would_block is true, 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.
If an error occurs then it issues an eror message and the stream should be closed. If the connection is closed or lost then it is considered an error condition.
If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function may block attempting to 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 stream_listen or 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 stream_listen.
Refer to Format Strings for Scanning for details on format strings.
This function does not support code generation.
stream
A stream handle returned by stream_connect or stream_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 scanf. 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.
fields
The number of complete fields read from the stream, which may be less than the number of fields in the format string if the maximum number of code units was reached before all the fields were read from the stream buffer. It may be zero for non-blocking streams if the operation would have blocked before all the data was read.
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_array(stream, 80, 'X: %lf'); % Scan the value of x from the stream
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-04-16. Submit feedback to Quanser about this page.
Link to this page.