scanf_unit (nst man page)

NAME

scanf_unit -- create unit to scan file or string

PROTOTYPES

unitptr scanf_unit( FILE *fp, char *pcFmt, int iMaxLen, unitptr uHost)

unitptr scanf_op( int iOperands, FILE *fp, char *pcFmt, int iMaxLen, unitptr uHost)

unitptr str_scanf_unit( char *pcFile, char *pcFmt, int iMaxLen, unitptr uHost)

unitptr str_scanf_op( int iOperands, char *pcFile, char *pcFmt, int iMaxLen, unitptr uHost)

ARGUMENTS

FILE *fp: file ptr specifying input file. For fp=NULL, input will be taken from input field X_in.
char *pcFmt: scanning format (similar to scanf()-format specification, see below)
int iMaxLen: allows to set upper limit on returned string tokens when conversion specifier has no max field size specification
unitptr uHost: host unit
int iOperands: nr of operand units
char *pcFile: input file, "-" selects stdin, "" string

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

INTERFACE OF CREATED UNIT:

X_in[1]:: (input field 0) a single pin of type string. Provides input if fp==NULL, ignored otherwise.
inp_1..k[2]:: for each %MmCc-field that specifies an input image, but gives no explicit offset specification (i.e., has only two arguments for image width and height), there will be a scalar input field of 2 pins to allow a dynamic specification of the desired image offset.
CTL_in[1]:: (input field 1) control input field. A value of zero disables execution of the present unit.

X_out[N]:: (mixed type output field 0) This field returns (a subset of) the tokens read during the scanning process. Returned tokens must be specified in the scanf-like conversion format string pcFmt, but with legal conversion characters restricted to d f s c n, * for assignment suppression, and [ ] and the hat-char to indicate negation within scan sets (for a description, see man scanf ).
There are some additionally allowed non-standard characters:
# and r are permitted to scan over comment lines and to auto-rewind at end of file (see below). V,v,M,m,C,c convert entire vectors or read monochrome or color images. For each returned token, X_out will have one or several (for vectors or color images) pin(s) of suitable type(s) (scalar float for d, f and n tokens, text string for s, char array for c, packed float field(s) for M, C, V and several scalar float pins for v ). Any tokens associated with conversion characters that are not in the above list are ignored.
Y_out[0]:: (unpacked output field 1) nr of pins for which tokens could be converted, -1 for EOF.
Z_out[N]:: (unpacked output field 2) a 1 in each position that corresponds to the position of a pin associated with a successfully converted token, a 0 for pins for which the token could not be converted, a -1 for each truncated token.

out_3[1]:: (only present for the scanf_op unit) current iteration count (0 during first iteration)

EXECUTION OF CREATED UNIT:

The scanf_unit scans an input file or (if fp==NULL) the string at its input field X_in according to the format string pcFmt and returns the successfully converted tokens at its output field X_out. The str_scanf - unit behaves similarly. The only difference is that files can be specified via a file name and different units that use the same file name will (internally) share the same file pointer. The scanf_op operator repeatedly uses pcFmt to read and convert tokens from an input file or the string at its input field X_in (if fp=NULL). After each complete scan (i.e., successful conversion of all tokens specified in pcFmt), the scanf_op operator provides the converted values at its output field X_out and executes its operand units. Then it increments the current iteration count (at out_3) by one and attempts the next scan. This continues until either a scan remained incomplete or the end of file or end of string is reached.

NON-STANDARD RECOGNIZED CONVERSION CHARS:

In addition to the usual scanf conversion chars, the following additional conversion characters are recognized:

v,V: (preceded by a single argument) convert float vector: read several float values (their number given by the preceding numeric argument) and assign their values to successive scalar float pins (for v ) or to a single packed float pin (for V ). Examples: %10v %10V

M,m: (preceded by 2 or 4 arguments) convert monochrome image from pgm file: read a text token, interprete it as the file name of a pgm file (suffix must be specified), read image (sub-)rectangle of the specified width and height (arguments 1 and 2 after %) from this file and assign pixel values to a vector (=packed) output pin of type float for 'M', byte for 'm'. Must be preceded by at least two colon-separated integers (width and height of read image rectangle). Two optional additional (possible negative) integers may specify an offset between the lower left corner of the image rectangle specified in the file and the image rectangle (which may have a different size) read by this unit. For each image that has no explicit offset parameters given, the scanf(_op) unit will have an additional input field of 2 pins that allow to specify an offset dynamically. If image sizes or offset are such that there is only partial overlap between the read image rectangle and the image rectangle in the file, those pixels of the read image rectangle that do not overlap with the rectangle in the file are set to 0. Examples: %80:80m %80:80:-30:50M. If the file turns out to contain color data, the average of the RGB channels is written into the output pin.

C,c: similarly to M,m but the file name read is expected to belong to a color image, for which three packed float (for 'C') or byte (for 'c') pins are assigned. If the file turns out to contain only monochrome data, only the red channel will receive data. NOTE: %80:80c is the format token for a 80x80 color image of bytes, whereas %80c is the format token for a 80 byte char vector!

-.! May immediately follow one of the image conversion specifiers 'm','M','C','c' and requests in this case an extra text output pin holding the file name of the image data file read. -.r Auto-rewind (see below) -.# skip comments (see below)

SKIPPING OF COMMENT LINES:

Each token %# in pcFmt is translated into a skip_comments() call and thus allows to scan over comment lines starting with a '#' -character. No assignment is caused by the %# token.

CONTROL MODES:

-NST_INIT : rewinds the accessed file. -NST_RESET : rewinds the accessed file. NST_OPEN rewinds the accessed file. Note that this will not change the current outputs of the unit. Only after the first exec_unit following a rewind will the data of the first file record appear at the outputs. When the token %r is present in pcFmt, encountering EOF during a scan will issue the NST_OPEN control call automatically. In non-operator mode (i.e., for iOperands=0 ), then a second scan is attempted.

FILE

/homes/jontrup/nst5/man/../o.sol2//../foldersrc/nst_string.c