c_cpp/etc/calc/help/fscanf

   1 NAME
   2     fscanf - formatted scan of a file stream
   3
   4 SYNOPSIS
   5     fscanf(fs, fmt, x_1, x_2, ...)
   6
   7 TYPES
   8     fs                  file stream open for reading
   9     fmt                 string
  10     x_1, x_2, ...       lvalues
  11
  12     return      null, nonnegative integer, or error value
  13
  14 DESCRIPTION
  15     If the current position for fs is EOF, the null value is returned.
  16
  17     Otherwise, until the terminating null character of fmt is encountered
  18     or end-of-file for fs is reached, characters other than '%' and white
  19     space are read from fmt and compared with the corresponding characters
  20     read from fs.  If the characters match, the reading continues.  If they
  21     do not match, an integer value is returned and the file position for
  22     fs is the position of the non-matching character.  If white space
  23     is encountered in fmt, any white space characters read from
  24     fs are skipped until either end-of-file is reached or a non-white-space
  25     character is read and comparisons continue under the control of the
  26     next non-white character and following characters in fmt.
  27
  28     When a '%' is encountered in fmt, if this is immediately followed by
  29     another '%', the pair is considered as if just one '%' were read and
  30     if reading from fmt and fs continues if and only if fs has a matching
  31     '%'.  A single '%' read from fmt is taken to indicate the beginning of
  32     a conversion specification field consisting in succession of:
  33
  34                 an optional '*',
  35                 optional decimal digits,
  36                 one of 'c', 's', 'n', 'f', 'e', 'i' or a scanset specifier.
  37
  38     A scanset specifier starts with '[' and an optional '^', then an optional
  39     ']', then optional other characters, and ends with ']'.   If any
  40     other sequence of characters follows the '%', characters before the
  41     first exceptional character (which could be the terminating null
  42     character of the fmt string) are ignored, e.g. the sequence " %*3d " does
  43     the same as " d ".  If there is no '*' at the beginning of the specifier,
  44     and the list x_1, x_2, ... has not been exhausted,
  45     a value will be assigned to the next lvalue in the list; if no lvalue
  46     remains, the reading of fs stops and the function returns the number
  47     of assignments that have been made.
  48
  49     Occurrence of '*' indicates that characters as specified are to be read
  50     but no assignment will be made.
  51
  52     The digits, if any, read at this stage in the specifier are taken to
  53     be decimal digits of an integer which becomes the maximum "width"
  54     (i.e. for string-type values, the number of characters to be read from
  55     fs); absence of digits or all zero digits in the 'c'
  56     case are taken to mean width = 1.  Zero width for the other cases are
  57     treated as if infinite.   Fewer characters than the specifier width
  58     may be read if end-of-file is reached or in the case of scanset
  59     specification, an exceptional character is encountered.
  60
  61     If the ending character is 'c', characters are read from fs to
  62     form a string, which will be ignored or in the non-'*' case, assigned
  63     to the next lvalue.
  64
  65     In the 's' case, reading to form the string starts at the first non-white
  66     character (if any) and ceases when end-of-file or further white space
  67     is encountered or the specified width has been attained.
  68
  69     The cases 'f', 'e', 'r', 'i' may be considered to indicate expectation of
  70     floating-point, exponential, ratio, or integer representation of the
  71     number to be read.  For example, 'i'
  72     might be taken to suggest a number like +2345; 'r' might suggest
  73     a representation like -27/49; 'e' might suggest a representation like
  74     1.24e-7; 'f' might suggest a representation like 27.145. However, there
  75     is no test that the result conforms to the specifier.  Whatever
  76     the specifier in these cases, the result depends on the characters read
  77     until a space or other exceptional character is read.  The
  78     characters read may include one or more occurrences of +, -, * as
  79     well as /, interpreted in the usual way, with left-to-right associativity
  80     for + and -, and for * and /.  Also acceptable is a trailing i to
  81     indicate an imaginary number.  For example the expression
  82
  83                         2+3/4*7i+3.15e7
  84
  85     would be interpreted as for an ordinary evaluation.  A decimal fraction
  86     may have more than one dot: dots after the first, which is taken to be
  87     the decimal point, are ignored.  Thus "12.3..45e6.7" is interpreted
  88     as if it were "12.345e67".
  89
  90     For the number specifiers 'f', 'e', 'r', 'i', any specified width is
  91     ignored.
  92
  93     For the specifier 'n', the current value of the file-position indicator
  94     is assigned to the corresponding lvalue. (Any width or skip specification
  95     is ignored.)
  96
  97
  98 EXAMPLE
  99     ; global a, b, c
 100     ; f = fopen("/tmp/junk", "w+")
 101     ; fputs(f, "Alpha Beta Gamma")
 102     ; rewind(f)
 103     ; fscanf(f, "Alpha Gamma")
 104     ; fgets(f)
 105         "Beta Gamma"
 106     ; rewind(f)
 107     ; fscanf(f, "%5c", a)
 108         1
 109     ; a
 110         "Alpha"
 111     ; fgets(f)
 112         " Beta Gamma"
 113     ; rewind(f)
 114     ; fscanf(f, "%3c%s%[^m]", a, b, c)
 115         3
 116     ; print a, b
 117     Alp ha
 118     ; print c
 119     Beta Ga
 120     ; fgets(f)
 121         "mma"
 122
 123 LIMITS
 124     The number of arguments is not to exceed 1024.
 125
 126 LINK LIBRARY
 127     extern int fscanfid(FILEID id, char *fmt, int count, VALUE **vals);
 128
 129 SEE ALSO
 130     scanf, strscanf, printf, fprintf, strprintf, fscan, scan, strscan
 131
 132 ## Copyright (C) 1999-2006  Landon Curt Noll
 133 ##
 134 ## Calc is open software; you can redistribute it and/or modify it under
 135 ## the terms of the version 2.1 of the GNU Lesser General Public License
 136 ## as published by the Free Software Foundation.
 137 ##
 138 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 139 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 140 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 141 ## Public License for more details.
 142 ##
 143 ## A copy of version 2.1 of the GNU Lesser General Public License is
 144 ## distributed with calc under the filename COPYING-LGPL.  You should have
 145 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 146 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 147 ##
 148 ## @(#) $Revision: 30.1 $
 149 ## @(#) $Id: fscanf,v 30.1 2007/03/16 11:10:42 chongo Exp $
 150 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/fscanf,v $
 151 ##
 152 ## Under source code control:   1996/04/30 03:05:18
 153 ## File existed as early as:    1996
 154 ##
 155 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 156 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/