NUMARG - extract numeric argument from character string.

Alternate Entry Name: .NMARG

Usage:

B:
   val = numarg( string [, position, base, flag] );

C:
   int numarg(const char *string [, int position,
              int base, int flag] );

Where:

string: is a pointer to the beginning of the string which contains the value or values to be extracted.
position: is the character position in the string where scanning should begin. The initial character of the string is in position zero, the next character is in position one, and so on. The default "position" is zero.
base: is the base of the number to be found. A "base" less than two (which is mathematically meaningless) implies that the number may be either decimal or octal, depending on the presence of leading zeroes. For bases greater than 10 (e.g. hexadecimal), the digits above nine are represented by the letters in lexicographical order. The default value for "base" is zero (so that numbers with a leading zero are taken to be octal and numbers without are taken to be decimal).
flag: is a word with the value 1, 0, or -1. A "flag" of 1 or -1 indicates that leading non-digits are to be ignored. A "flag" of zero indicates that leading non-digits are not to be ignored. If "flag" is not specified, the default is zero.

Description:

NUMARG extracts a possibly signed number from the given string. All arguments except the first are optional. Furthermore, parameters "position" and "flag" may be passed by value or by pointer, so that one may write

number = numarg(string, cursor, 10, flag);

number = numarg(string, &cursor, 10, &flag);

If "position" is passed by pointer, it is updated by the function to point at the character position where the scan stopped. If the scan is successful, this will be the character position after the number. If the scan is unsuccessful, then it points to the first character that could not be part of the number. NUMARG may thus be used rather like GETARG to get a sequence of numbers from a string, as follows.

cursor = 0;
num1 = numarg(string, &cursor);
num2 = numarg(string, &cursor);
num3 = numarg(string, &cursor);
. . .

NUMARG determines whether it is being passed a position or a pointer to a position by checking the value of the argument which it is passed. If "position" is less than 100, it is assumed to be an actual character offset; if "position" is 100 or more, it is assumed to POINT to the character offset. Thus you cannot specify an explicit character offset of more than 99.

If "flag" is passed by pointer, it is used as a status return word. "flag" is assumed to be a pointer if it is not -1, 0, or 1. NUMARG will set the word pointed to by "flag" to indicate whether or not a numerical argument was obtained, and the calling program can thus test this word to see if NUMARG was successful. If no number is found in "string" or if "position" is invalid, the word pointed to by "flag" is set to -1. Otherwise, it is set to zero.

NUMARG returns a zero to "val" if no number is found in "string". NUMARG always ignores leading blanks when scanning through "string".