String Print

Prints formatted data to a string.

Library

Description

The String Print block prints formatted data to a string, much like sprintf prints to a string. The output is a UTF-8 string expressed as a null-terminated vector of uint8 characters that can be used by any of the QUARC blocks that support strings. The string that is output always has the maximum length specified in the Maximum number of code units to print parameter.

For a description of the format strings, refer to Format Strings for Printing.

This block formats its inputs according to the given format string and then writes the formatted textual result its output. If an error occurs formatting the text, then it returns a negative error code at its err output. Otherwise it outputs the number of code units (bytes) written to the string to this port.

The size of the output is determined by the Maximum number of code units to print parameter. The block will never write beyond this maximum length. If the formatted text would exceed this maximum then the string is truncated at the maximum length. The output is always null terminated. The number of fields processed successfully is output at the flds port.

The String Print block also supports a variable-size output string. To generate a variable-size output string, check the Use variable-size output option. If the output is variable-size, then its width will be equal to the length of the string currently output (including the null terminator). If that length exceeds the maximum length specified in the Maximum number of code units to print parameter then it is truncated to the maximum length. See Variable-Size Signals for more information on variable-size signals.

Input Ports

...

Subsequent input ports contain the data to be formatted. The number of input ports is determined by the number of format specifiers, such as %lg, in the specified format string. The %n format specifier does not produce an input port. Instead it causes an output port to be created. All other valid format specifiers cause corresponding input ports to be created. Variable-sized field widths, precisions and code unit specifiers also cause input ports to be created in order to specify the field width, precision or maximum number of code units. Inputs corresponding to string or variable dimension format specifiers may be variable-size signals.

Output Ports

str

The string containing the formatted data. It is a vector of UTF-8 (uint8) characters whose length is determined by the Maximum number of code units to print parameter. The string is always null-terminated. If the Use variable-size output option is checked then this output is variable-size. Refer to Variable-Size Signals for more information on variable-size signals.

...

Subsequent output ports, with the exception of the last two ports, are used for %n specifiers in the format string, which produce the number of code units processed up to that point in the format string.

flds

An int32 value indicating the number of fields from the format string that were written to the string successfully and fully. This number may be less than the number of fields defined in the format string if the maximum number of code units was reached before all the fields were written to the string. If an error occurs, then this value indicates the number of fields that could be written successfully, which may assist in locating the source of the error.

err

An int32 value indicating whether the formatted text was written to the string successfully. This value will be the number of code units printed unless an error occurs. If an error occurs then this value is a negative error code. See Error Codes for the different error codes and their values. Use the Compare to Error block rather than the error code itself to check for specific error codes. To check for errors in general use the Compare to Zero block to check whether err output is less than zero.

Data Type Support

For scalar quantities, the String Print block accepts signals of any of the built-in Simulink data types at its data inputs. Fixed point is not currently supported. It does support writing the output string as a variable-size output.

For array quantities, as indicated by a dimension specifier in the format string, the String Print block only accepts signals of the data type corresponding to the format specifier at that port.

Parameters and Dialog Box

Format string

The format string used to format the data. Refer to the Format Strings for Printing page for a description of the format string. This parameter is treated as a string literal. It is not evaluated. Hence, do not enclose the format string in quotes unless you wish the quotes to appear in the output.

Maximum number of code units to print

This parameter restricts the total number of code units written to the string. This limit is a hard limit. The total number of code units written to the string will never exceed this limit, even if the output for an input port is truncated or all the input ports have not been included in the output.

Use variable-size output

Enabling this option causes the str output to be variable-size. In this case, the size of the output varies with the length of the printed string, including the null terminator. If this option is not checked then the output is a fixed-size vector equal to the Maximum number of code units to print. See Variable-Size Signals for more information on variable-size signals.

Targets

See Also

• Format Strings for Printing
• String Scan block
• String Constant block
• String Display block

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.

Link to this page.