stream_print :: QUARC MATLAB Functions

navigation bar

stream_print

Prints formatted text to a stream.

Syntax

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

Description

This function prints formatted text to the stream buffer. 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 no code units could be sent without blocking, then would_block is set to true (1). This behaviour is different from the stream_print_array function, which will only print the entire formatted text (if it can do so without blocking) or nothing at all (if it would block).

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.

Warning

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.

Parameters

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.

Outputs

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.

Examples

num_chars = stream_print(stream, 80, 'Value: %lf', x);    % Print the value of x to the stream