strscanf

Calc Software Package for Number Calc

NAME
    strscanf - formatted scan of a string

SYNOPSIS
    strscanf(str, fmt, x_1, x_2, ...)

TYPES
    str			string
    fmt			string
    x_1, x_2, ...	lvalues

    return	null, nonnegative integer, or error value

DESCRIPTION
    If the str is "", the null value is returned.

    Otherwise, until the terminating null character of either fmt or str
    is reached, characters other than '%' and whitespace are read from
    fmt and compared with the corresponding characters read from str.
    If the characters match, reading continues.	 If they do not match
    an integer value is returned.  If whitespace is encountered in fmt,
    starting at the current positions in fmt and str, any whitespace
    characters are skipped and reading and comparison begins as before
    if neither fmt nor str has reached its end.

    When a '%' is encountered in fmt, if this is immediately followed by
    another '%', the pair formed is considered as if one '%' were read and
    reading from fmt and fs continues if and only if fs has a matching
    '%'.  A single '%' read from fmt is taken to indicate the beginning of
    a conversion specification field consisting in succession of:

		an optional '*',
		optional decimal digits,
		one of 'c', 's', 'n', 'f', 'e', 'i' or a scanset specifier.

    A scanset specifier starts with '[' and an optional '^', then an optional
    ']', then optional other characters, and ends with ']'.   If any
    other sequence of characters follows the '%', characters before the
    first exceptional character (which could be the terminating null
    character of the fmt string) are ignored, e.g. the sequence " %*3d " does
    the same as " d ".	If there is no '*' at the beginning of the specifier,
    and the list x_1, x_2, ... has not been exhausted,
    a value will be assigned to the next lvalue in the list; if no lvalue
    remains, the reading of fs stops and the function returns the number
    of assignments that have been made.

    Occurrence of '*' indicates that characters as specified are to be read
    but no assignment will be made.

    The digits, if any, read in the specifier are taken to be decimal digits
    of an integer which becomes the maximum "width" (number of characters
    to be read from str for string-type assignments); absence of digits or
    all zero digits in the 'c' case are taken to mean width = 1.  Zero width
    for the other cases are treated as if infinite.   Fewer characters than
    the specifier width may be read if end-of-file is reached or in the case
    of scanset specification, an exceptional character is encountered.

    If the ending character is 'c', characters are read from fs to
    form a string, which will be ignored or in the non-'*' case, assigned
    to the next lvalue.

    In the 's' case, reading to form the string starts at the first non-white
    character (if any) and ceases when end-of-file or further white space
    is encountered or the specified width has been attained.

    The cases 'f', 'e', 'r', 'i' may be considered to indicate expectation of
    floating-point, exponential, ratio, or integer representation of the
    number to be read.	For example, 'i'
    might be taken to suggest a number like +2345; 'r' might suggest
    a representation like -27/49; 'e' might suggest a representation like
    1.24e-7; 'f' might suggest a representation like 27.145. However, there
    is no test that the the result conforms to the specifier.  Whatever
    the specifier in these cases, the result depends on the characters read
    until a space or other exceptional character is read.  The
    characters read may include one or more occurrences of +, -, * as
    well as /, interpreted in the usual way, with left-to-right associativity
    for + and -, and for * and /.  Also acceptable is a trailing i to
    indicate an imaginary number.  For example the expression

			2+3/4*7i+3.15e7

    would be interpreted as for an ordinary evaluation.	 A decimal fraction
    may have more than one dot: dots after the first, which is taken to be
    the decimal point, are ignored.  Thus "12.3..45e6.7" is interpreted
    as if it were "12.345e67".

    For the number specifiers 'f', 'e', 'r', 'i', any specified width is
    ignored.

    For the specifier 'n', the index of the next character to b e read
    is assigned to the corresponding lvalue. (Any width or skip specification
    is ignored.)


EXAMPLE
    ; global a, b, c, d
    ; A = "abc xyz 234.6 alpha"
    ; strscanf(A, "%s%*[^0123456789]%f%n", a, b, c)
	3
    ; print a, b, c
    ; abc 234.6 13

    ; strscanf(A, "%*13c%s", d);
	1
    ; print d
    ; alpha

LIMITS
    The number of arguments is not to exceed 1024.

LINK LIBRARY
    int fscanfid(FILEID id, char *fmt, int count, VALUE **vals);

SEE ALSO
    strcat, strcpy, strerror, strlen, strncmp, strncpy, strpos,
    strprintf, strscan, substr

## Copyright (C) 1999-2006  Ernest Bowen
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.
##
## @(#) $Revision: 29.4 $
## @(#) $Id: strscanf,v 29.4 2006/06/25 22:16:55 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/strscanf,v $
##
## Under source code control:	1996/04/30 03:05:18
## File existed as early as:	1996
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/