Scan String — Control Systems/Strings

Scan String

Control Systems / Strings

Reads values out of text by a format, one output per conversion, as Simulink's Scan String does. With the Format "%d %f" (the default) and the text 42 3.5, output 1 is 42 and output 2 is 3.5. It is not C's sscanf: every rule below was measured on Simulink, and several of them differ from C.

Ports

• Input (str, ICoreString) – the text, one value.
• Output 1 (i32, ICoreInt32, for the default Format's %d) – one value [1,1].
• Output 2 (f32, ICoreSingle, for the default Format's %f) – one value [1,1].

There is one output per conversion, in order; the number of outputs is yours to set and must equal the number of conversions in the Format. What each output carries is decided by its conversion, exactly as in Simulink: %d and %ld a 32-bit integer (i32), %hd a 16-bit one (i16), %u and %lu an unsigned 32-bit integer (u32), %hu an unsigned 16-bit one (u16), %f, %e and %g a single (f32), %lf, %le and %lg a double (f64), %s and %c text (str, ICoreString).

Parameters

• Format – the format, written with its quotes as in Simulink: "%d %f" (the default). A doubled quote inside is one quote. A conversion is %, an optional width, an optional h or l, and one of d u f e g s c; any other character must be matched exactly by the text; %% matches a percent sign; the escapes \n, \t, \r, \a, \b, \f, \v and \\ match the control characters they name. Between 1 and 128 conversions, Simulink's own limits.
• Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.

How the text is read

• Each character of the Format that is not a conversion – a space included – must match exactly one identical character of the text: "%d %d" does not read 1<tab>2, and " %d" does not read 5. The first character that does not match STOPS the scan, and every later output is 0 or empty text.
• A number skips white space first (space, tab, newline, vertical tab, form feed, return), then reads an optional +, an optional -, and then Inf (a capital I, then n and f in either case), NaN (any case), or decimal digits – with a fraction for %f, %e and %g and without one for %d and %u, whose exponent is still read: %d of 1e3 is 1000 and of 3.9 is 3. An exponent is read only when digits follow it. Hexadecimal is not read.
• A number that is not there is not a stop: the output is 0 and the scan goes on from the same place ("%d%s" of abc is 0 and abc).
• An integer conversion cuts the number toward zero into a 64-bit integer that saturates (NaN is 0) and keeps its low 32 or 16 bits: %d of 1e10 is 1410065408, of Inf is -1; %u of -5 is 4294967291. Digits beyond what a double holds are kept exactly.
• A single is the double nearest the text, rounded again to single.
• %s skips white space and takes the characters up to the next white space; %c skips nothing and takes one character, or as many as its width. A width limits what a conversion may take after the white space it skipped, signs included – except a leading +, which is skipped with the white space and costs nothing: "%2d" of -123 is -1 and of +123 is 12.

What is not offered

Each of these stops the run with a message naming it: %i, %x, %o, %X, %E, %G, %n, a *, a flag such as %-d or %0d, a precision (%5.2f), hh, ll and L – all refused by Simulink too – and scansets such as %[abc], which Simulink accepts and this block does not.

Code export

C, C++, Python, MATLAB, Java and Rust all read the same values: each carries the same small scanner, written out in the language, and turns digits into numbers with the language's own correctly rounded parser. The Format is read when the code is generated, not when it runs.

VHDL, Verilog and SystemVerilog do not carry text, and PLC Structured Text is not supported either: the language has a string type, but the check that runs an exported core cannot read one back. An export to any of these four stops and names this block and the reason.

Simulink bridge

Import and export, mapped to simulink/String/Scan String. "Format" crosses unchanged, quotes and all; on import the number of outputs and what each one carries are read off it, since Simulink derives both from the Format as well. simulink/String/String to Double and String to Single are this same block with the Format preset to "%lf" and "%f" (measured: the same block type, the same one-parameter dialog), and they import as this block with that Format; they export back as Scan String. The Simulink block has no sampling-time setting of its own, so a positive Sampling Time (s) stays on this side and is reported rather than written.

Notes

• Algebraic, with no state: the outputs depend only on the current input.
• Widths, %s and %c count bytes of UTF-8 here – the same count as Simulink's for plain ASCII text.
• One measured corner is not reproduced: Simulink saturated an in-range value written as an 18-digit mantissa with an exponent – the value eight below 2⁶³, so still inside the 64-bit range – where this block keeps it. Integer text of 18 digits or fewer is not affected.