stream_print_array
Prints formatted text to a stream as an atomic unit.
[code_units, num_fields, would_block, ...] = stream_print_array(stream, max_code_units, format_string, ...)
This function prints formatted text to the stream buffer as an atomic unit. It attempts to store all the formatted text store in the stream buffer as an array of characters. If there is enough room available in the stream buffer then it stores the formatted text in the buffer and returns immediately. The text is not written to the actual communication channel until the stream is flushed using stream_flush or there is no more room available in the stream buffer. If an error occurs, then it issues an error message. If the connection is closed 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 flush the stream buffer. All the text will be consumed and the total number of code units sent is returned. Some of the text may remain in the stream buffer and not be sent until the next time stream_flush is called or there is no more room available in the stream buffer. If an error occurs then an error is issued and the stream should be closed.
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 successfully printed, which will be at least 1 unless the format string is empty. If all the code units could not be sent without blocking,
then would_block is set to true (1) and nothing is written to the stream buffer. Hence, the entire formatted text may be reprinted and no duplicate text will appear in
the output. This behaviour is different from the
stream_print function, which will output as many fields as it can without blocking.
If an error occurs then an error is issued and the stream should be closed.
This operation is not valid on listening streams created using stream_listen.
| Note that when using code generation, the %n format specifier is not allowed. Also, the data types of arguments MUST match the type implied by the corresponding format specifier in the format string. |
stream
Stream handle returned by stream_connect or stream_accept.
max_code_units
The maximum number of code units to write to the underlying stream. The text will be truncated if this limit would be exceeded.
format_string
A format string akin to the C library function printf. Note however that more options are available, such as the ability to print arrays using a single format specifier. Refer to Format Strings for Printing for details on format strings.
...
Additional arguments corresponding to each format specifier in the format string.
code_units
The number of code units actually written to the stream buffer, which may be less than max_code_units for non-blocking streams. For blocking streams, a value of 0 is returned only if the format string array is empty.
num_fields
The number of fields actually written completely to the stream buffer, 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 written to the stream buffer.
would_block
Whether the function would have blocked. Always false for blocking streams.
...
Additional output arguments corresponding to %n format specifiers in the format string.
num_chars = stream_print_array(stream, 80, 'Value: %lf', x); % Print the value of x to 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.