iifGetNum bb#,nn,fw [D>=28]
W = (float){Ascii2Decimal[(bb+I)..(bb+I+min(fw,nn))]}; I = I+{number of characters consumed}; R = (valid result) ? 0 : 1
Extract (Get) a floating point number from a buffer in RAM.
Consider an Xwire receive data block to be nn bytes of RAM long, starting at address bb. Return a decimal number from the data block, starting at RAM address bb+I (i.e. the starting address is indexed). Skip any leading spaces. Process leading + or – sign, if present. Terminate on anything thereafter that’s not a decimal digit or decimal point, or after processing fw (field width) characters in total (including spaces, sign and decimal point). Advance I past the characters used, leaving it pointing at the terminating character (auto-index). Result in W, NaN if nothing there. R register signals outcome. 0 = OK, 1 = no valid decimal number present.
Notes:
- Typically used for receiving ASCII-coded information from an Xwire peripheral board.
- The field width
fwincludes leading spaces, signs and decimal point. - Conversion will end on the first unexpected character, including a second sign character, a second decimal point or a trailing space. This overrides the field width.
- The valid range for
fwis 1 to 255.fw= 255 disables character counting. - Anything more than 7 digits of input is meaningless, as the floating point number representation is only accurate to 6 or 7 decimal places. Excess digits will be nevertheless be consumed, up to the limits of
nnandfw.
Dialect exclusions: Not available in dialects before 28
See also: iifPrintWFW, iifPrintWVW,
Examples
The following shows the result of the instruction iifGetNum 100,15,8 for various RAM contents and Values of I.
| Data in RAM, starting at address 100 (Shown as ASCII (printable) characters. | Initial value of I | Result returned in W | Final value of I | Comment |
123.456xxxxxxxx | 0 | 123.456 | 7 | Conversion starts at the first character, because I = 0. Conversion is terminated by the first x. |
123.456xxxxxxxx | 1 | 23.456 | 7 | Conversion starts at the second character, because I = 1. |
123.456xxxx | 0 | 123 | 8 | Leading spaces are counted in the field width. The decimal point “makes it”, and I gets left pointing at the 4. A subsequent conversion with the same instruction would return 456 |
-123.456xxxxxxx | 0 | -123.456 | 8 | All good, got it all |
-123.456xxxxxx | 0 | -123.45 | 8 | The last digit is excluded, because the field width of 8 terminates conversion. Furthermore, a subsequent conversion would return 6. |
-12.3.456xxxxxx | 0 | -12.3 | 6 | The second decimal point terminates conversion. If the same instruction were executed again (with I as-is), it would return 0.456 |