FString

FString

FString(editMask, constantText), FString(STACK, STACK ).

This command implements the formatting function used internally by the FormattedString widget.

This formatting function translates arbitrary strings into a corresponding formatted string. The formatting is defined via the parameters editMask and constantText . If editMask is empty, then no formatting is applied and the string is returned exactly the same.

The FString function maps unformatted strings into a space of formatted strings (defined by editMask and constantText). Strings that are already formatted are not changed by this function. The function is thus idempotent, which is an important property of the FString function, so that executing PutValue&GetValue or FillWindow&DrainWindow on a FormattedString widget does not change an already formatted value again, as the value should only change if the user has made an input or the format has changed. The need for the idempotency of this function also explains some somewhat strange rules when processing the editMask.

Note: The behaviour described here corresponds to the behaviour as of Dll version 224610. Before that, FString was not idempotent and the semantics were not clearly defined. The behaviour of the following editMask characters has changed as a result 0,#,K,L,N.

Functionality

The editMask defines at which position in the input/output what kind of characters are expected and thus also the maximum length of the formatted string. The formatted string is never longer than the editMask.

The input string is formatted by going through the editMask character by character and, depending on the mask character, starting from the last position, searching for a corresponding character in the input and taking it over into the output text. For each character that is read in the editMask, a corresponding character is also read from the constantMask at the same position. The constantMask should therefore have the same length as the editMask. The characters from the constantMask are read in the FString command only for the mask k,K.

In the FormattedString widget, the constantMask is used to define the text that is to be inserted in place of the deleted characters when they are deleted. Accordingly, the constantMask should always represent a valid input for the editMask.

When searching for a suitable character, it can also happen that the input no longer contains a suitable character. The input position is then placed at the end of the input and all subsequent elements of the editMask behave as described in the table in the column "if empty".

Mask character

¹⁼"" here means that nothing is written to the output and "0" means that only a 0 is written to the output.

²⁼ Since N still produces an output if the input is empty, it is potentially executed multiple times (see special rule K&N).

³⁼ This means that the input position is advanced by one character if the current character of the input matches the character current character from constantText . If this is not the case, the input position is not changed. In both cases, however, the same output is produced. (See special rule K)

4= The blanks must be counted in the mask "####" so that the function is idempotent. Otherwise, the mask "##0" with the input "1" would first generate the output " 10" and, when executed again, the output "100".

5= This placeholder is used by the FormattedString widget to insert the corresponding placeholder from constantText at this position in the text field. However, this placeholder is never included in the output.

Explanation of special rules

mask k,K

The mask K always writes the character from the current position in constantText into the output. If this character also matches the current character from the input, then the position in the input is advanced by one place. Otherwise, the input position is not changed (in contrast to A,C,N&X, the input is not searched for the character).

This special treatment is necessary for FString to be idempotent.
Example:

If K would never advance the input, then the second application in the example would have resulted in "AB--123".
If K would search the input, then the first application in the example would have resulted in "AB-000".

There is no difference between using k and K. In both cases, the character is taken 1:1 from the constantMask.

Implicit multiple use of k,K and n,N.

Since the masks A,C,X do not produce any output if the input is empty, the mask K and N can extend the output string, since an output is generated even if the input is empty. By clever combination with other masks, a format can thus be defined which, in the case of an empty input, would only produce a fully formatted text after multiple applications of FString, which no longer changes. Since FString must be idempotent, such cases are recognised and FString is called again internally on the result.

Examples:

mask #...#

The mask "#" defines a formatting field that accepts 0-n digits, where n corresponds to the number of # characters. If such a field is reached in the editMask, then all characters in the input that are not digits or spaces are skipped. Then leading spaces are read in from the input text (are treated like leading 0's) and then the digits themselves. The leading spaces are treated like 0's and are also counted in the number of digits.

This behaviour differs from the mask "0...0", which works very similarly, but skips leading blanks completely and does not count them among the digits. However, this distinction is necessary for FString to be idempotent. As soon as a real digit is found, all characters that are not digits are counted as the end of the input for this field.

Examples:

If #...# leading spaces did not count as digits, then the format "##0" with the input "1" would first return " 10" and, when executed again, "100".

Mask l,L

The mask L (and the corresponding character from the constantText) is completely ignored when using this formatting function. L defines a placeholder that is only observed by the FormattedString widget and ensures that the character from the constantText is displayed as a placeholder in the widget at this point. This placeholder only serves as a guide for the input and with GetValue the placeholder created by L is not returned and with PutValue it is also not expected in the input.

Since L , in contrast to K, is completely read over, the explicit specification of the placeholder in PutValue ensures that the input is sometimes not interpreted as expected by the user.

Example:

If L were to read over the placeholder in the input, if it occurs in it, then FString("LAA", "AAA") would progressively shorten the input "AAA" to "", which is not the behaviour of a placeholder used only for representation within.

Examples