Legacy Document

str2dec

You can use the str2dec function to convert a decimal string to a decimal structure.

void str2dec (const char *s, short *ix, decimal *d, short *vp); 

s

The character string containing the number to be converted.

ix

On entry, the starting position in the string. On return, one greater than the position of the last character in the string that was parsed if the entire string was not converted successfully.

d

On return, a pointer to the decimal structure containing the decimal number. See page 9-13 for a description of the decimal structure.

vp

On return, a Boolean argument indicating the success of the function. If the entire string was parsed, vp is true. If part of the string was parsed, vp is false and ix indicates where the function stopped parsing.

DESCRIPTION

The str2dec function is the PowerPC Numerics scanner, which is designed for use both with fixed strings and with strings being received interactively character by character. The scanner parses the longest possible numeric substring; if no numeric substring is recognized, then the value of ix remains unchanged.

To convert floating-point strings embedded in text, parse to the beginning of a floating-point string ([+ | -] digit) and pass the current scan location as the index into the text. The conversion routine will return the value scanned and a new value of the index for continued parsing.

You might need to distinguish those numeric ASCII strings that represent values of an integer format. You can do this by scanning the source, looking for integer syntax. You can handle integers yourself and send to the numeric scanner any strings with floating-point syntax (that is, containing a period (.), an E, or an e). You might also want to pass along to the scanner any strings that cause integer overflow.

EXCEPTIONS

The scanner signals no exceptions. It faithfully converts all values within range that are representable in the decimal structure format.

SPECIAL CASES

To convert a zero, NaN, or Infinity, use one of the following as input:

-0

+0

0

-INF

Inf

NAN

-NaN()

nan

EXAMPLES

Listing 9-2 shows an example of how to scan decimal strings into an application and then convert the strings to binary floating-point numbers using MathLib functions. Table 9-10 shows some sample inputs to the loop shown in Listing 9-2 and the results after each string has been converted to a decimal structure using str2dec.

Listing 9-2 Scanning algorithm

s = "";        /* initialize string */

/* loop until string is not a valid prefix*/
do
  {

   /* code to get next character and append to string goes here */

   /* scan string */
  ix = 0;
  str2dec(s, &ix, &d, &vp);
  }
while (vp = false);

/* convert from decimal to numeric-format result */
result = dec2num(d);

Table 9-10 Examples of conversions to decimal structures

Input string	Index	Output value	Valid prefix
	In Out
12	0 2	12	True
12E	0 2	12	True
12E-	0 2	12	True
12E-3	0 5	12E\xC73	True
12E-X	0 2	12	False
12E-3X	0 5	12E\xC73	False
x12E-3	1 6	12E\xC73	True
IN	0 0	NAN	True
INF	0 3	INF	True