help/strscanf

   1 NAME
   2     strscanf - formatted scan of a string
   3
   4 SYNOPSIS
   5     strscanf(str, fmt, x_1, x_2, ...)
   6
   7 TYPES
   8     str                 string
   9     fmt                 string
  10     x_1, x_2, ...       lvalues
  11
  12     return      null, nonnegative integer, or error value
  13
  14 DESCRIPTION
  15     If the str is "", the null value is returned.
  16
  17     Otherwise, until the terminating null character of either fmt or str
  18     is reached, characters other than '%' and whitespace are read from
  19     fmt and compared with the corresponding characters read from str.
  20     If the characters match, reading continues.  If they do not match
  21     an integer value is returned.  If whitespace is encountered in fmt,
  22     starting at the current positions in fmt and str, any whitespace
  23     characters are skipped and reading and comparison begins as before
  24     if neither fmt nor str has reached its end.
  25
  26     When a '%' is encountered in fmt, if this is immediately followed by
  27     another '%', the pair formed is considered as if one '%' were read and
  28     reading from fmt and fs continues if and only if fs has a matching
  29     '%'.  A single '%' read from fmt is taken to indicate the beginning of
  30     a conversion specification field consisting in succession of:
  31
  32                 an optional '*',
  33                 optional decimal digits,
  34                 one of 'c', 's', 'n', 'f', 'e', 'i' or a scanset specifier.
  35
  36     A scanset specifier starts with '[' and an optional '^', then an optional
  37     ']', then optional other characters, and ends with ']'.   If any
  38     other sequence of characters follows the '%', characters before the
  39     first exceptional character (which could be the terminating null
  40     character of the fmt string) are ignored, e.g. the sequence " %*3d " does
  41     the same as " d ".  If there is no '*' at the beginning of the specifier,
  42     and the list x_1, x_2, ... has not been exhausted,
  43     a value will be assigned to the next lvalue in the list; if no lvalue
  44     remains, the reading of fs stops and the function returns the number
  45     of assignments that have been made.
  46
  47     Occurrence of '*' indicates that characters as specified are to be read
  48     but no assignment will be made.
  49
  50     The digits, if any, read in the specifier are taken to be decimal digits
  51     of an integer which becomes the maximum "width" (number of characters
  52     to be read from str for string-type assignments); absence of digits or
  53     all zero digits in the 'c' case are taken to mean width = 1.  Zero width
  54     for the other cases are treated as if infinite.   Fewer characters than
  55     the specifier width may be read if end-of-file is reached or in the case
  56     of scanset specification, an exceptional character is encountered.
  57
  58     If the ending character is 'c', characters are read from fs to
  59     form a string, which will be ignored or in the non-'*' case, assigned
  60     to the next lvalue.
  61
  62     In the 's' case, reading to form the string starts at the first non-white
  63     character (if any) and ceases when end-of-file or further white space
  64     is encountered or the specified width has been attained.
  65
  66     The cases 'f', 'e', 'r', 'i' may be considered to indicate expectation of
  67     floating-point, exponential, ratio, or integer representation of the
  68     number to be read.  For example, 'i'
  69     might be taken to suggest a number like +2345; 'r' might suggest
  70     a representation like -27/49; 'e' might suggest a representation like
  71     1.24e-7; 'f' might suggest a representation like 27.145. However, there
  72     is no test that the the result conforms to the specifier.  Whatever
  73     the specifier in these cases, the result depends on the characters read
  74     until a space or other exceptional character is read.  The
  75     characters read may include one or more occurrences of +, -, * as
  76     well as /, interpreted in the usual way, with left-to-right associativity
  77     for + and -, and for * and /.  Also acceptable is a trailing i to
  78     indicate an imaginary number.  For example the expression
  79
  80                         2+3/4*7i+3.15e7
  81
  82     would be interpreted as for an ordinary evaluation.  A decimal fraction
  83     may have more than one dot: dots after the first, which is taken to be
  84     the decimal point, are ignored.  Thus "12.3..45e6.7" is interpreted
  85     as if it were "12.345e67".
  86
  87     For the number specifiers 'f', 'e', 'r', 'i', any specified width is
  88     ignored.
  89
  90     For the specifier 'n', the index of the next character to b e read
  91     is assigned to the corresponding lvalue. (Any width or skip specification
  92     is ignored.)
  93
  94
  95 EXAMPLE
  96     > global a, b, c, d
  97     > A = "abc xyz 234.6 alpha"
  98     > strscanf(A, "%s%*[^0123456789]%f%n", a, b, c)
  99         3
 100     > print a, b, c
 101     > abc 234.6 13
 102
 103     > strscanf(A, "%*13c%s", d);
 104         1
 105     > print d
 106     > alpha
 107
 108 LIMITS
 109     none - XXX - is this correct?
 110
 111 LINK LIBRARY
 112     none - XXX - is this correct?
 113
 114 SEE ALSO
 115     fscanf, scanf, fscan, strscan, scan, print, printf
 116