String Subset

Extracts a contiguous range of characters from a string.

Library

QUARC Targets/Strings

Description

The String Subset block is similar to the Selector block that is provided with Simulink except that it selects characters out of strings (i.e. null-terminated vectors of uint8 characters) rather than numeric values.

The range of characters to extract from the input string is determined by the source of the range specification and the indexing mode. The source of the range specification may be dialog parameters or external inputs. The indexing mode determines how the range is actually specified. There are three possible modes:

• exclusive range

• inclusive range

• range by length

In the exclusive range indexing mode, the zero-based index of the starting character is provided, as well as the zero-based index of the character which ends the range. In the exclusive mode the character that ends the range is not included in the extracted substring. This mode is useful in conjunction with the Host Speech Synthesis block for extracting the word or sentence currently being spoken from the output string.

In the inclusive range indexing mode, the zero-based index of the starting character is provided, as well as the zero-based index of the character which ends the range. In the inclusive mode the character that ends the range is included in the extracted substring.

In the range by length mode, the zero-based index of the starting character is provided as well as the number of characters to extract.

When the range is specified via external inputs, two extra inputs are provided for specifying the range. If the Use vector input option is checked then only one extra input is provided, labeled rng and the range is specified as a two-vector at this extra input.

The String Subset block handles ranges that exceed the range of the string. If the range denotes an empty subset of the input string then it will output an empty string. Simulink's built-in Selector block cannot produce empty vectors at its output.

If the starting or ending indices specified are negative then they are considered relative to the end of the string. Hence, to extract the character beginning with the last three characters of the string, regardless of the string length, specify a starting index of -3.

One-based indexing is not currently supported. Indices are based on characters not code units. Hence, multibyte UTF-8 characters count as a single character with regards to the starting or ending indices. Hence, characters can never be split.

The String Subset block supports variable-size input and output strings. To generate a variable-size output string, select the variable-size signal option for the Output dimensions mode parameter or allow the dimensions mode to be inherited from the input string. Variable-size input strings are supported regardless of the state of the Output dimensions mode parameter. See Variable-Size Signals for more information on variable-size signals.

Input Ports

str

The string from which to extract the characters. The input must be a null-terminated vector of UTF-8 (uint8) characters. It may be a variable-size signal.

start

The index of the character at the start of the range of characters to extract. It is a zero-based index so a value of zero indicates the first character in the string. This input is only provided when the Source of range parameter is set to Use external inputs and the Use vector input option is not checked.

end

The index of the character which ends the range of characters to extract. It is a zero-based index. Whether the ending character is included in the range or not depends on the Indexing mode setting. This input is only provided when the Source of range parameter is set to Use external inputs, the Indexing mode is configured for either the exclusive or inclusive range and the Use vector input option is not checked.

If the ending index is greater than the length of the string, then all the characters from the starting index to the end of the string will be extracted.

len

The number of characters to extract i.e., the length of the substring in characters. This input is only provided when the Source of range parameter is set to Use external inputs, the Indexing mode is configured for range by length and the Use vector input option is not checked.

If the starting index plus the length is greater than or equal to the length of the string, then all the characters from the starting index to the end of the string will be extracted.

rng

A two-vector specifying the range of characters to extract from the input string. This input is only provided when the Source of range parameter is set to Use external inputs and the Use vector input option is checked.

The meaning of the two elements depends on the Indexing mode. The first element is always the starting index. The second element is either the ending index or the length of the substring.

Output Ports

str

The subset of characters extracted from the input string. The data type of this output is uint8 (UTF-8 code unit), which is the data type used by QUARC for strings. The string is guaranteed to be null-terminated. It will be a fixed-size or variable-size signal depending on the Output dimensions mode and input string.

Data Type Support

This block outputs the string as a null-terminated vector of UTF-8 characters or uint8 values. The input signals must be the same data type, but may be any length. Variable-size signals are supported for both the input and output strings. Any of the standard Simulink data types may be used for the inputs used to specify the range. See Variable-Size Signals for more information on variable-size signals.

Parameters and Dialog Box

Source of range

The source of the range specification. If this parameter is set to specify via dialog then the range of characters to extract is specified via dialog parameters. If it is set to use external inputs then extra input ports are provided for specifying the range.

Indexing mode (tunable online)

The indexing mode used for extracting characters from the input string. The indexing mode determines how the range of characters to extract is specified. Set it to exclusive range to specify the range as a zero-based starting and ending index in which the character at the ending index is excluded from the extracted substring.

Set the index mode to inclusive range to specify the range as a zero-based starting and ending index in which the character at the ending index is included in the extracted substring.

Finally, set the index mode to range by length to specify the range as a zero-based starting index and a length.

Starting index (tunable online)

This parameter is only available when the Source of range parameter is specify via dialog. It specifies the zero-based index of the character at the start of the range of characters to extract from the input string.

Ending index (tunable online)

This parameter is only available when the Source of range parameter is specify via dialog and the Indexing mode is either exclusive range or inclusive range. It specifies the zero-based index of the character at the end of the range of characters to extract from the input string. Whether this character is excluded or included in the substring is determined by the indexing mode.

Specify double(intmax) to extract all the characters from the starting index to the end of the string. If you don't plan on tuning this parameter then intmax is sufficient (using intmax alone causes the parameter to have a data type of int32 when most MATLAB expressions return double values).

Length of substring (tunable online)

This parameter is only available when the Source of range parameter is specify via dialog and the Indexing mode is range by length. It specifies the number of characters to extract from the input string beginning at the starting index.

Specify double(intmax) to extract all the characters from the starting index to the end of the string. If you don't plan on tuning this parameter then intmax is sufficient (using intmax alone causes the parameter to have a data type of int32 when most MATLAB expressions return double values).

Use vector input

This parameter is only available when the Source of range parameter is use external inputs. It causes the external inputs for specifying the starting and ending index or length of the range to be combined into a single vector input instead.

Output dimensions mode

This parameter determines whether the str output is a fixed-size signal or a variable-size signal. For a variable-size output, the maximum size of this output is equal to the size of the input string. However its length will vary dynamically with the size of the extracted substring. The default is to inherit the dimensions mode from the input string so that a variable-size signal at the input will produce a variable-size signal at the output and otherwise the output is fixed-size. Refer to Variable-Size Signals for more information on variable-size signals.

Targets

See Also

• String Accumulate block
• String Concatenate block
• String Constant block
• String Display block
• String Select 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.