String Select

Outputs a string from a list of strings based on the input.

Library

QUARC Targets/Strings

Description

The String Select block is similar to the String Constant block except that the string it outputs is selected from a list of strings according to the input signal. The list of strings is a block parameter. The input signal is a zero-based index into the list of strings. The output string is a null-terminated vector of uint8 characters. The string that is output always has the maximum length specified in the Maximum length parameter. If this parameter is zero then it uses the length of the longest string in the list, or the the length of the default string, whichever is larger.

The String Select block allows the strings in the list to contain format specifiers. These format specifiers begin with a '%' character and are replaced with the appropriate value. For example, the date and time at which the model was started may be substituted using the '%{date}' and '%{time}' expressions in the string. Refer to the qc_perform_substitutions function for a full list of the format specifiers available. It also replaces standard C escape sequences such as '\n' with the appropriate ASCII character.

If format specifiers which change frequently, such as '%{time}' or '%{instance}', are used in the string value then the String Select block cannot be placed in a referenced model, because the value will change from the time the code is built to when the code is run. As a result, Simulink will insist that the code be rebuilt because block parameters in referenced models are inlined. Instead, use the String Select block in the top-level model and pass its output as a signal from the top-level model to an input port of the referenced model.

When using format specifiers, sometimes characters are added to the string that are not desirable under the circumstances. For example, the string returned by '%{time}' includes colons because it takes the form 'HH:MM:SS'. If the output string is intended as a filename, then these colons would result in an illegal filename.

Since the time can be quite useful for data logging as part of a filename, QUARC resolves this problem via the String type parameter. The String type option may be used to coerce the resulting string into a particular format. For example, setting the String type parameter to file forces the output to be a valid file path. In this case, if '%{time}' were part of the string value then the output of the String Select block would contain the time, but the colons would be replaced with hyphens, which are valid in a filename.

The input signal selects which string is output. The value may range from 0 to one less than the number of strings in the list. A value of 0 accesses the first string in the list, and the items are numbered sequentially from there. If the input signal is not within the range of valid indices then the Default string is output instead. By default, this string is empty.

The String Select 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 length parameter then it is truncated to the maximum length. See Variable-Size Signals for more information on variable-size signals.

Input Ports

idx

A zero-based index into the list of strings. Its value may range from zero to one less than the number of strings in the list. Any value outside this range will result in the value entered as the Default string parameter being output instead of a string from the list.

Output Ports

str

The string selected from the list. The string is represented as a null-terminated vector of UTF-8 characters or uint8 values. The length of the vector is always equal to the size entered in the Maximum length parameter. If the Use variable-size output option is checked then this output is variable-size.

Data Type Support

This block outputs the string as a null-terminated vector of UTF-8 characters or uint8 values. The input signal may be any of the standard Simulink numeric types. Fixed-point datatypes are not currently supported. It does support writing the output string as a variable-size output. Refer to Variable-Size Signals for more information on variable-size signals.

Parameters and Dialog Box

List of strings (tunable offline)

The list of strings. Each entry may include format specifiers. Refer to the qc_perform_substitutions function for a list of format specifiers available.

To add a string to the list, enter the string in the edit field below the list of strings and then click on the Add button, which has a "+" on it. The arrow button to the right of the edit field may be used to select format specifiers to append to the string value. New strings are inserted in the list after the item that is currently selected.

To remove a string from the list, click on the string in the list. Then push the Remove button, which has a "-" on it.

To change the value of a string in the list, click on the string in the list. The value of that item will appear in the edit field below the list of strings. Edit the value in this field. Then push the Change button, which has an "=" on it.

Since strings are selected by their index in the list, the order of the strings is important. To move a string upward in the list, click on the string in the list. Then push the Up button, which has an upward arrow on it.

To move a string downward in the list, click on the string in the list. Then push the Down button, which has a downward arrow on it.

Default string (tunable offline)

This field contains the string that will be output if the input is outside the valid range of indices. For example, if there are five items in the list and the input is less than zero or greater than or equal to five, then the default string will be output. This string may be empty.

String type (tunable offline)

This option indicates the purpose for which the string is being used and coerces the output of the String Select block accordingly. The table below enumerates the different string types.

Maximum string length

The maximum length of the output string in code units (bytes), including the null-terminator. The output will be a vector of this length. If this parameter is zero then the maximum string length is computed as the maximum of all the strings in the list and the default string.

Use variable-size output

Enabling this option causes the str output to be variable-size. In this case, each time a different string is selected, the size of the output varies. If this option is not checked then the output is a fixed-size vector. See Variable-Size Signals for more information on variable-size signals.

Targets

See Also

• String Constant block
• String Display block
• String Print block

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

Link to this page.