Table of Contents
String Select
Outputs a string from a list of strings based on the input.
Library
MATLAB Command Line
Click to copy the following command line to the clipboard. Then paste it in the MATLAB Command Window:
qc_open_library('quarc_library/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
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.If you are using the keyboard to navigate the block parameters, use the Alt+Down key combination on the arrow button to open the drop-down list of format specifiers. |
To remove a string from the list, click on the string in the list. Then push the
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
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
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
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.
Type |
Description |
---|---|
text |
The string is straightforward text. No changes are made to the resulting output. |
file |
The string is intended as a filename. Illegal characters are removed or replaced. |
URI |
The string is intended as a URI. Illegal characters are removed or replaced. |
variable |
The string is intended as a variable name. Illegal characters are removed or replaced and the string may be truncated to namelengthmax
.
MATLAB Command Line Click to copy the following command line to the clipboard. Then paste it in the MATLAB Command Window: doc namelengthmax |
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
Target Name |
Compatible* |
Model Referencing |
Comments |
---|---|---|---|
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
Last fully supported in QUARC 2018. |
|
Rapid Simulation (RSIM) Target |
Yes |
Yes |
|
S-Function Target |
No |
N/A |
Old technology. Use model referencing instead. |
Normal simulation |
Yes |
Yes |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.