NAME _ScanF -- Input data from standard input SYNOPSIS count,stream = _ScanF(string,arguments...) d0 a0 a0 (a1)+ FUNCTION Input a sequence of variables in a format defined by a format string. INPUTS char *string - This is a null terminated string which represents the format in which to input the subsequent arguments. This string consists of printable characters and escape sequences which begin with the percent symbol ('%'). (Note that to read a percent symbol you need to put '%%' in the format string). Whitespaces in the format string will match against (ie. skip past) zero or more whitespace characters in the input stream. Therefore it is inadvisable to put whitespaces at the end of a format string (as the user could end up pressing newline forever). Non-whitespaces in the format string will be compared with the next character from the input stream. If they match then the character is skipped over, otherwise _ScanF() aborts and no further items will be input. (You can check how many items were successfully input by looking at the return value). For details of allowable escape sequences see below. APTR arguments... - These are pointers to variables which are to be assigned. ESCAPE SEQUENCES Escape sequences for _ScanF() have the following syntax: %[][][] The various fields (listed in reverse order) are as follows: This is a single character which determines the type of the corresponding argument. Allowable values are: c Input a character. The corresponding argument must be passed as a (char *) and represents the address at which to store a single character. C Input a character translated to upper case. The corresponding argument must be passed as a (char *) and represents the address at which to store a single character. s Input a string. The corresponding argument must be passed as a (char *) and represents the address of a buffer into which to write a C-style null-terminated string. The string is considered to be terminated by the first whitespace encountered in the input stream (unless modified by the '+' flag - see below). S Input a string translated to upper case. The corresponding argument must be passed as a (char *) and represents the address of a buffer into which to write a C-style null-terminated string. The string is considered to be terminated by the first whitespace encountered in the input stream (unless modified by the '+' flag - see below). b Input a string. The corresponding argument is a BPTR and represents the address of a buffer into which a BSTR will be written. The string is considered to be terminated by the first whitespace encountered in the input stream. B Input a string translated to upper case. The corresponding argument is a BPTR and represents the address of a buffer into which a BSTR will be written. The string is considered to be terminated by the first whitespace encountered in the input stream. i,I Input an integer in decimal, hexadecimal or octal. If the number begins with '0x', '0X' or '$' then it is interpretted as hexadecimal; else if it starts with '0' or '&' then it is interpretted as octal; else it is interpretted as decimal. Numbers may be preceeded by zero or more whitespace characters and an optional sign ('+' or '-'). The corresponding argument may be passed as a (WORD *) (by default) or a (LONG *) (if the 'l' size-modifier is present) and represents the address at which to store the integer value. d,D,u,U Input an integer in decimal. Numbers may be preceeded by zero or more whitespace characters and an optional sign ('+' or '-'). The corresponding argument may be passed as a (WORD *) (by default) or a (LONG *) (if the 'l' size-modifier is present) and represents the address at which to store the integer value. o,O Input an integer in octal. Numbers may be preceeded by zero or more whitespace characters, an optional sign ('+' or '-'), and optionally an '&' character. The corresponding argument may be passed as a (WORD *) (by default) or a (LONG *) (if the 'l' size-modifier is present) and represents the address at which to store the integer value. x,X Input an integer in hexadecimal. Numbers may be preceeded by zero or more whitespace characters, an optional sign ('+' or '-'), and optionally '0x', '0X' or '$'. The corresponding argument may be passed as a (WORD *) (by default) or a (LONG *) (if the 'l' size-modifier is present) and represents the address at which to store the integer value. f,F,g,G,e,E Input a floating point number in either standard decimal notation or scientific notation. The corresponding argument may be passed as a pointer to an ieee single precision float (by default) or a pointer to an ieee double precision float (if the 'l' size-modifier is present). [^] This is a square left bracket ('[') followed by an up-arrow ('^') followed by a sequence of any characters (excluding null and square right bracket) followed by a square right bracket (']'). Input a string terminated by any character in the list. The corresponding argument must be passed as a (char *) and represents the address of a buffer into which to write a C-style null-terminated string. Note that the terminating character is put back into the input stream and will be the next character read. [] This is a square left bracket ('[') followed by a a sequence of any characters (excluding null and square right bracket, and not beginning with up-arraow) followed by a square right bracket (']'). Input a string containing only characters in the specified list. The corresponding argument must be passed as a (char *) and represents the address of a buffer into which to write a C-style null-terminated string. This is a single character which determines the size of the corresponding argument. Allowable values are: h For types d and i this declares the corresponding argument to be of type (WORD *). For types u, o and x this declares the corresponding argument to be of type (UWORD *). For types e,f and g this declares the corresponding argument to be of type (float *). Note that this is the default. l For types d and i this declares the corresponding argument to be of type (LONG *). For types u, o and x this declares the corresponding argument to be of type (ULONG *). For types e,f and g this declares the corresponding argument to be of type (double *). This is an integer (expressed in decimal) which denotes the maximum number of characters to read from the input stream for the given argument. This is a set of zero or more of the following flags, which may occur in any order: + This flag is only used with %s. It allows you to input strings which contain whitespace, by accepting possibly enquoted strings from the input stream. Enquoted strings are strings surrounded by either single or double quotes. The delimiter character is allowable inside such a string by supplying it twice. Note that the string will be written into your buffer WITHOUT surrounding quotes, and with double-delimiters translated back to single-delimiters. / Toggle the case of any alphabetic character. This may be used in conjunction with %S to translate a string to lower case, for example. * Scan the value, but DO NOT WRITE IT TO A VARIABLE. You do not need to supply a pointer variable to correspond to this escape sequence. This may be used to skip over known datatypes in the input stream. RESULTS ULONG count - This is a count of the number of items of data which have been input, or may be -1 in the event of an error. void *stream - This result is only available to machine code programmers. If there were more arguments supplied than escape sequences in the format string then this will be the address of the first unused argument. EXAMPLE To input a time in the form , but allowing the user a choice of separator: _ScanF("%d %*[,.:-/] %d %*[,.:-/] %d",&hours,&minute,&seconds); NOTES Machine code programmers will find the functions _ScanF() and _VScanF() to be identical. Only C programmers can tell them apart. SEE ALSO _ScanF(),_SScanF(),_VSScanF(),_FScanF(),_VFScanF() HookScanF(),VHookScanF(),BRawScanF(),RawScanF(). Also _PrintF() and related functions and _GetS() and related functions.